package it.uniroma3.dia.ia.textcategorization.datasource;

import it.uniroma3.dia.ia.textcategorization.model.Category;
import it.uniroma3.dia.ia.textcategorization.model.Text;

import java.util.Set;

/**
 * 
 * This interface declares the methods of the objects responsible
 * for the exploration of and the data extraction from a data source.
 * 
 * @author Marco Liceti
 *
 */
public interface DataSource {
	
	/**
	 * 
	 * Returns the top level categories for this DataSource.
	 * 
	 * @return the top level categories.
	 * 
	 */
	Set<Category> getTopLevelCategories();
	
	/**
	 * 
	 * Returns the names of the subcategories of the
	 * given category.
	 * 
	 * @param category The category whose subcategories have to be returned.
	 * @return the subcategories' names.
	 * 
	 */
	Set<String> getSubcategoriesNamesFor(Category category);
	
	/**
	 * 
	 * Returns the number of texts available for the given Category.
	 * WARNING: depending on the DataSource implementation, this method
	 * may take very long to get executed.
	 * 
	 * @param category The Category whose Texts have to be counted.
	 * @return the number of text available.
	 */
	long getNumberOfTextsAvailableFor(Category category);
	
	/**
	 * 
	 * Tries (but doesn't guarantees) to return the requested number of Text instances for
	 * the given Category. Before calling this method,
	 * ensure that the DataSource contains an adequate number of texts
	 * for the Category.
	 * WARNING: depending on the DataSource implementation, this method
	 * may take very long to get executed.
	 * 
	 * @param category  The Category whose Texts have to be returned.
	 * @param numberOfTexts The number of Text instances to extract.
	 * @return the Text instances for the Category
	 */
	Set<Text> getTexts(Category category, long numberOfTexts);

}
